Alias

CscCredentialsInfo

Description

Obtains a signature credential (i.e., a signing identity) of a user.

Request

To obtain a signature credential of a user, the client application must send the following request to the TRIDENT using TLS.

POST /trustedx-resources/csc/v2/credentials/info

Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be /csc/v2/. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is /csc/v2 instead of /trustedx-resources/csc/v2. To determine if this is the case in your situation, check the "oauth2" property of the JSON object provided by the Obtain information on the CSC signature service operation.

Content-Type Header

Content-Type: application/json

Request Parameters

Name	Type	Usage	Description
`credentialID`	String	Required	Identifier of the signature credential to be obtained.
`certificates`	String	Optional	Indication whether either the certificate that forms part of the credential ("`single`"), the complete certificate chain of the certificate ("`chain`") or neither of these ("`none`") is to be returned in the response. I.e.: "`none`": no certificate. "`single`": user's signing certificate. "`chain`": user's signing certificate and the complete certificate chain. The default value is "`single`".
`certInfo`	Boolean	Optional	Indication whether information on the certificate that forms part of the credential is to be returned in the response. This information may be useful if the signature application needs information on the certificate but does not want to have to decode it. The default value is `false`.

Authorization

The request must contain a bearer access token with the service scope. As a rule, obtaining this token via either an authorization code grant or client credentials grant OAuth 2.0 flow is possible. When the token is obtained through an OAuth 2.0 Authorization Code Grant, the user whose credentials list is requested is implicit in the token, so the userID request parameter should not be used.

The access token must be put in the Authorization header, as explained in RFC 6750. I.e., as follows:

Authorization: Bearer <token>

Response

Status-Line

If the request is successfully processed, the HTTP response contains the following Status-Line:

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object that contains the information of a signature credential .

{
    "description": {string},
    "signatureQualifier": {string},
     "key": {
           "status": {string},
           "algo": [{string}],
           "len": {number}
     },
     "cert": {
           "status": {string},
           "certificates": [{string}],
           "issuerDN": {string},
           "serialNumber": {string},
           "subjectDN": {string},
           "validFrom": {string},
           "validTo": {string}           
    },
     "authMode": {string},
     "SCAL": {string},
     "multisign": {number},
     "lang": {string}     
}

Property	Type	Description
`description`	String	Descriptive text (in the language specified in the `lang` property and limited to 255 characters) of the signature credential provided.
`signatureQualifier`	String	This property is only present if the "`signatureQualifier`" parameter was present in the credentials authorization request to obtain the `credentialID.` Identifier qualifying the type of signature for which this credential is suitable. The only value supported is `"eu_eidas_qes"`, and it means that the signing key associated with the credential is suitable for qualified electronic signatures as per the EU eIDAS regulation.
`key/status`	String	Status of the signing key associated with the signature credential: `"enabled"`: the signing key is enabled and can be used to generate signatures. `"disabled"`: the signing key is disabled and cannot be used to generate signatures.
`key/algo`	String Array	List of OIDs of the signature algorithms that can be used with the signing key associated with the signature credential. The elements of the list can be one or more of the following: "`1.2.840.113549.1.1.1`": RSA encryption "`1.2.840.113549.1.1.11`": sha256WithRSAEncryption "`1.2.840.113549.1.1.12`": sha384WithRSAEncryption "`1.2.840.113549.1.1.13`": sha512WithRSAEncryption "`1.2.840.10045.4.3.2`": sha 256WithECDSA " `1.2.840.10045.4.3.3`": sha384 WithECDSA " `1.2.840.10045.4.3.4`": sha512 WithECDSA
`key/curve`	String	OIDs de la c urvas elíptica de la clave de firma asociada a la credencial de firma. "`1.2.840.10045.3.1.7`": secp256r1 " `1.3.132.0.34`": secp384r1 "`1.3.132.0.35`": secp512r1
`key/len`	Number	Size in bytes of the signing key associated with the signature credential.
`cert/status`	String	Status of the signing certificate that forms part of the signature credential: "`valid`": the signing certificate is valid. "`expired`": the signing certificate has expired.
`cert/certificates`	String Array	This property is only present if the value of the "`certificates`" parameter of the request is "`single`" or "`chain`" "`single`": `cert/certificates` contains the signing certificate that forms part of the signature credential (encoded in base64). "`chain`": `cert/certificates` contains the signing certificate that forms part of the signature credential (encoded in base64) and its complete certificate chain (with the certificates of this chain encoded in base64).
`cert/issuerDN`	String	This property is only present if the value of the "`certInfo`" parameter is true and contains the DN of the issuer (Issuer Distinguished Name) of the signing certificate that forms part of the signature credential.
`cert/serialNumber`	String	This property is only present if the value of the "`certInfo`" parameter is `true` and contains the serial number (Serial Number) of the signing certificate that forms part of the signature credential.
`cert/SubjectDN`	String	This property is only present if the value of the "`certInfo`" parameter is true and contains the DN of the subject (Subject Distinguished Name) of the signing certificate that forms part of the signature credential.
`cert/ValidFrom`	String	This property is only present if the value of the "`certInfo`" parameter is `true` and contains the start time of the validity period of the signing certificate that forms part of the signature credential with the `YYYYMMDDHHMMSSZ` format.
`cert/ValidTo`	String	This property is only present if the value of the "`certInfo`" parameter is true and contains the end time of the validity period of the signing certificate that forms part of the signature credential, with the `YYYYMMDDHHMMSSZ` format.
`authmode`	String	Mode for obtaining authorization from the user for using the signing key associated with the signature credential to generate a signature. Always has "`oauth2code`" as value, i.e., an Authorization Code Grant OAuth 2.0 flow must be performed, and a token with the `credential` scope must be obtained.
`SCAL`	String	Level that must be achieved to demonstrate exclusive control (by the user) of the signing key associated to the signature credential to be able to generate signatures with it (see [EN 419 241-1] ) : 1: SCAL1 level is required: signatures generated with the signing key will be advanced electronic signatures. 2: SCAL2 level is required: signatures generated with the signing key will be qualified electronic signatures.
`multisign`	Number	The maximum number of signatures that one user's authorization allows generating with the signing key associated with the signature credential (see also the `numSignatures` parameter in Obtain an OAuth 2.0 authorization).
`lang`	String	Language used in the response (in the `description` property). This will be the value specified by an administrator in the settings of the CSC service. The language is specified as per [RFC 5646].

Error Management

If the request does not contain the Authorization: Bearer header, the TRIDENT returns an HTTP response with the 401 Unauthorized Status Code.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the Content-Type: application/json;charset=utf-8 header and a JSON object in the body with the following properties:

error: Error code.
error_description: Additional description of the error. Not required.

Error case	Status Code (HTTP)	error	error_description
The `credentialID` parameter was not included in the request, or its value is not a String.	400 Bad Request	`invalid_request`	`invalidParameter`
The `credentialID` parameter of the request is invalid.	400 Bad Request	`invalid_request`	`invalidCredentialId`
The `certificates` parameter of the request is invalid.	400 Bad Request	`invalid_request`	`invalidParameter`

Example

Request

The signature application requests the signature credential identified by "GX0112348". For this, it sends the following request to the TRIDENT specifying in it that it wants to receive information on the signing certificate along with the certificate:

POST /trustedx-resources/csc/v2/credentials/info HTTP/1.1
Host: rse.corporation.com
Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597
Content-Type: application/json
 
{    
    "credentialID": "GX0112348",
    "certificates": "single",
    "certInfo": true
}

Response

The TRIDENT responds to the signature application providing it with the signature credential requested.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "description": "Corporative signature credential",
    "key": {
        "status": "enabled",
        "algo": [
            "1.2.840.113549.1.1.13",
            "1.2.840.113549.1.1.1",
            "1.2.840.113549.1.1.11",
            "1.2.840.113549.1.1.12"
        ],
        "len": 2048
    },
    "cert": {
        "certificates": ["MIIFpTCCBI2...m1SEW"],
           "serialNumber": "67210661094051074244364068313147966416",
           "validFrom": "20210120121230Z",
           "validTo": "20220120121230Z",
           "issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\", 
                        OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",
           "subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"
    },
    "authMode": "oauth2code",
    "multisign": 40,
    "lang": "en-US",
    "SCAL": "2"
}  